[TDR Generic表][Java SDK]插入单条数据

1. 接口说明

向指定的表格中插入一条新数据。

当表格中已存在相同Key的数据时，数据将插入失败。

2. 版本要求

无特殊要求，所有版本都提供了该接口。

3. 准备工作

参见准备工作文档，完成使用该接口前的准备工作，并创建TDR Generic表。

准备工作完成后，将会获得以下信息，这些信息在使用SDK时会被用到：

  1. 目录服务器地址列表
  2. 业务ID
  3. 业务访问密码
  4. 游戏区ID
  5. 数据表名

4. 示例代码

示例代码的基本执行过程：

  1. 创建客户端；
  2. 构建请求；
  3. 发送请求；
  4. 处理响应；
  5. 销毁客户端。

4.1. 同步调用示例代码

import com.tencent.tcaplus.client.Client;
import com.tencent.tcaplus.client.ClientFactory;
import com.tencent.tcaplus.client.Record;
import com.tencent.tcaplus.client.Request;
import com.tencent.tcaplus.client.Response;
import com.tencent.tdr.tcaplus_protocol_cs.TcaplusProtocolCsConstants;

import java.util.ArrayList;
import java.util.List;

public class Example {

    public static void main(String[] arguments) {
        // 1. 准备环境信息
        // 1.1. 目录服务器地址列表
        List<String> dirList = new ArrayList<String>();
        dirList.add("tcp://x.x.x.x:9999");
        dirList.add("tcp://y.y.y.y:9999");
        // 1.2. 业务ID
        int appId = 1;
        // 1.3. 业务访问密码
        String appPassword = "****************";
        // 1.4. 游戏区ID
        int zoneId = 1;
        // 1.5. 数据表名
        String tableName = "test";

        // 2. 创建客户端
        Client client = ClientFactory.createClient(appId, zoneId, appPassword, dirList);
        try {
            // 3. 构造插入数据的请求
            // 3.1. 获取请求对象。为了提升SDK性能，Request对象是复用的
            Request request = client.acquireRequest();
            // 3.2. 设置请求类型和目标表名
            request.setCmd(TcaplusProtocolCsConstants.TCAPLUS_CMD_INSERT_REQ);
            request.setTableName(tableName);
            // 3.3. 设置数据各字段的值，这里要注意Key字段和Value字段，使用的是不同的方法设置字段值
            Record record = request.addRecord();
            record.setKeyInt("gameid", 1);
            record.setKeyInt("itemid", 1);
            record.setKeyString("name", "test");
            record.setValueByte("typeid", (byte) 1);
            record.setValueByte("Data", (byte) 1);
            record.setValueString("uname", "test");

            // 4. 发送请求，并获取结果
            Response response = client.poll(request);

            // 5. 处理响应
            if (response.getResult() == 0) {
                // 插入数据成功
                // TODO 可在此处添加数据插入成功的后续处理代码
            } else {
                // 插入数据失败
                // TODO 可在此处添加数据插入失败的后续处理代码
            }
        } finally {
            // 6. 销毁客户端对象
            ClientFactory.destroyClient(client);
        }
    }

}

4.2. 异步调用示例代码

import com.tencent.tcaplus.client.Client;
import com.tencent.tcaplus.client.ClientFactory;
import com.tencent.tcaplus.client.Record;
import com.tencent.tcaplus.client.Request;
import com.tencent.tcaplus.client.Response;
import com.tencent.tdr.tcaplus_protocol_cs.TcaplusProtocolCsConstants;

import java.util.ArrayList;
import java.util.List;

public class Example {

    public static void main(String[] arguments) {
        // 1. 准备环境信息
        // 1.1. 目录服务器地址列表
        List<String> dirList = new ArrayList<String>();
        dirList.add("tcp://x.x.x.x:9999");
        dirList.add("tcp://y.y.y.y:9999");
        // 1.2. 业务ID
        int appId = 1;
        // 1.3. 业务访问密码
        String appPassword = "****************";
        // 1.4. 游戏区ID
        int zoneId = 1;
        // 1.5. 数据表名
        String tableName = "test";

        // 2. 创建客户端
        Client client = ClientFactory.createClient(appId, zoneId, appPassword, dirList);
        try {
            // 3. 构造插入数据的请求
            // 3.1. 获取请求对象。为了提升SDK性能，Request对象是复用的
            Request request = client.acquireRequest();
            // 3.2. 设置请求类型和目标表名
            request.setCmd(TcaplusProtocolCsConstants.TCAPLUS_CMD_INSERT_REQ);
            request.setTableName(tableName);
            // 3.3. 设置数据各字段的值，这里要注意Key字段和Value字段，使用的是不同的方法设置字段值
            Record record = request.addRecord();
            record.setKeyInt("gameid", 1);
            record.setKeyInt("itemid", 1);
            record.setKeyString("name", "test");
            record.setValueByte("typeid", (byte) 1);
            record.setValueByte("Data", (byte) 1);
            record.setValueString("uname", "test");

            CountDownLatch latch = new CountDownLatch(1);

            // 4. 异步发送请求，并指定返回结果处理器，post方法会立即返回
            client.post(request, new Future() {

                @Override
                public void onResponse(Response response) {
                    // 5. 处理响应
                    if (response.getResult() == 0) {
                        // 插入数据成功
                        // TODO 可在此处添加数据插入成功的后续处理代码
                    } else {
                        // 插入数据失败
                        // TODO 可在此处添加数据插入失败的后续处理代码
                    }
                }

            });

            latch.await();
        } finally {
            // 6. 销毁客户端对象
            ClientFactory.destroyClient(client);
        }
    }

}

5. 请求对象中的方法说明

注：此处未列出请求对象的其它方法，即表示该方法在插入数据的场景不需要使用，误用可能会导致报错。

方法签名 方法说明
void setCmd(int cmd) 设置请求类型（命令字）。
cmd：请求类型，固定为TcaplusProtocolCsConstants.TCAPLUS_CMD_INSERT_REQ。
void setTableName(String tableName) 设置目标表名。
tableName：目标表名，不能为null。
Record addRecord() 添加和获取新数据对象（Record），用户随后可以调用该对象的setXXX方法设置新数据各字段的值。

5.1. 数据对象中的方法说明

插入数据的场景主要使用到数据对象的setXXX接口，用于设置新数据的字段值。

注：TcaplusDB支持无符号整数（unsigned）类型字段，然而Java语句不支持无符号整数，因此在字段值超出Java对应类型的取值范围（Java中表现为负数）时，需要业务自行将负数转换为正数。 注：此处未列出的数据对象的其它方法，即表示该方法在插入数据的场景不需要使用，误用可能会导致报错。

方法签名 方法说明
void setVersion(int version) 设置记录的版本号。
version：如果设置为负数，表示当前数据不启动版本控制。
版本控制主要用于乐观锁等场景。
void setKeyByte(String fieldName, byte value) 设置指定名称的Key字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的byte类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setKeyShort(String fieldName, short value) 设置指定名称的Key字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的short类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setKeyInt(String fieldName, int value) 设置指定名称的Key字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的int类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setKeyLong(String fieldName, long value) 设置指定名称的Key字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的long类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setKeyFloat(String fieldName, float value) 设置指定名称的Key字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的float类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setKeyDouble(String fieldName, double value) 设置指定名称的Key字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的double类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setKeyString(String fieldName, String value) 设置指定名称的Key字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的String类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setKeyBlob(String fieldName, byte[] value) 设置指定名称的Key字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的byte[]类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setValueByte(String fieldName, byte value) 设置指定名称的Value字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的byte类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setValueShort(String fieldName, short value) 设置指定名称的Value字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的short类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setValueInt(String fieldName, int value) 设置指定名称的Value字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的int类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setValueLong(String fieldName, long value) 设置指定名称的Value字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的long类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setValueFloat(String fieldName, float value) 设置指定名称的Value字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的float类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setValueDouble(String fieldName, double value) 设置指定名称的Value字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的double类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setValueString(String fieldName, String value) 设置指定名称的Value字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的String类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。
void setValueBlob(String fieldName, byte[] value) 设置指定名称的Value字段的值。
fieldName：字段名称，不可为null。value：字段的新值。
注意：当TDR表描述文件中定义的字段类型与Java的byte[]类型对应时，才可调用该方法设置字段值，否则服务端在处理请求时会报参数错误。参见TDR表字段类型与Java类型对应关系。

6. 响应对象中的方法说明

注：此处未列出的响应对象的其它方法，即表示该方法在插入数据的场景不需要使用，误用可能会导致报错。

方法签名 方法说明
int getResult() 获取插入数据请求的响应码。
0表示操作成功。非0表示操作异常，常见的错误码有：
-1293：同Key的数据记录已存在。
更多错误码参见错误码含义和处理方法。

7. 常见问题

详见错误码含义和处理方法。

8. 其它参考文档

[TDR Generic表][C++ SDK]插入单条数据接口说明

[TDR Generic表][Go SDK]插入单条数据接口说明

[TDR Generic表][MySQL协议兼容接口]插入数据接口说明

results matching ""

    No results matching ""